Quickstart

This guide will ensure you're fully prepared to navigate the Bento API. We'll walk you through the initial setup using one of our API clients and how to execute your first API request. Additionally, we'll explore the resources available to help you maximize the capabilities of our REST API.

Choose your client

We offer a range of open-source libraries for multiple programming languages, enabling seamless interaction with the Bento API. The supported features can be found on each library's GitHub page. Besides using cURL for HTTP requests, Bento offers SDK clients for JavaScript, Laravel, PHP, Ruby, Next.js, Node.js, and a WordPress WooCommerce plugin. The following example shows how to install each client.

# cURL is most likely already installed on your machine
curl --version

For any queries, feedback, or issues, please open an issue on the respective GitHub repository. Your contributions and insights help us improve and evolve continuously.

Making your first API request

Once you've chosen your preferred client, you're ready to make your first call to the Bento API. Below, you'll find instructions on sending a GET request to the Tags endpoint to return all tags in your account.

  curl -L -X GET 'https://app.bentonow.com/api/v1/fetch/tags?site_uuid=YourSITEUUID1234' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [base64 of Publishable Key and Secret Key]'

Common Setups/Patterns

99.99% of Bento users will follow similar patterns when using our product. They send us real-time events for user behaviour, as well as regularly sync their data to our platform. Some will use us for transactional emails too.

To do all of that, we only need to hit 3 API endpoints.

Start by tracking user activity using /v1/batch/events using our SDKs or API.

This one single API call will:

1. Create an event
2. Create a user in your account if they do not exist
3. And can be used to update custom fields.

You do not need to call the API to create a user beforehand or do multiple calls after to update fields.

Additionally, these events can be used to trigger automations.

curl -L -X POST 'https://app.bentonow.com/api/v1/batch/events?site_uuid=ExampleID1234' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)' \
--data-raw '{
      "events": [
        {
          "type": "account.signup",
          "email": "[email protected]",
          "fields": {
            "first_name": "Jesse",
            "last_name": "Pinkman"
          }
        }
      ]
}'

Running regular syncs of user data using /v1/batch/subscribers using our SDKs or API.. This endpoint is great as it mimics our CSV upload API which does not trigger automations. This makes it a perfect pairing for syncing user data to ensure it's always up to date.

  curl -L -X POST 'https://app.bentonow.com/api/v1/batch/subscribers?site_uuid=ExampleID1234' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic BASE64ENCODE(USERNAME+PASSWORD)' \
    --data-raw '{
      "subscribers": [
        {
          "email": "[email protected]",
          "first_name": "John",
          "last_name": "Doe",
          "tags": "lead,mql",
          "remove_tags": "customers",
          "some_other_field": "some value"
        }
      ]
    }'

Finally, you can use /v1/batch/emails to send transactional emails (or one of our various libraries/SDKs). This endpoint is great for sending emails such as password resets or emails that are incredibly time sensitive. For emails that are not time sensitive, we perhaps recommend instead sending in an event and using an automation to send the email as you have the ability to edit the content in our app instead of needing to supply HTML to our API (better for collaboration).

bento.V1.Batch.sendTransactionalEmails({
  emails: [
    {
      to: '[email protected]',
      from: '[email protected]',
      subject: 'Reset Password',
      html_body: '<p>Here is a link to reset your password ... {{ link }}</p>',
      transactional: true,
    },
  ],
})

BONUS: At this point, you are getting most of the utility out of Bento but you may want to track user behaviour client-side as well. This is where our Javascript SDK comes in.

<!-- GET THIS CODE IN YOUR ACCOUNT -->
<script src="https://app.bentonow.com/{...}.js" async defer></script>
<script>
  window.addEventListener("bento:ready", function () {
    if (typeof(bento$) != 'undefined') {
      bento$(function() {
        // NOTE: When a user is logged in, you want to run bento.identify(email) BEFORE you call bento.view()
        // This will ensure that all their events are attributed to the correct user.
        // if (logged_in) {
          // bento.identify(email);
        // }
        bento.view();
      });
    }
  })
</script>

And now you're done! That was easy, right! 🎉

API Details

Rate Limits

Rate limits are enforced to maintain API stability and prevent excessive usage, ensuring a seamless experience for all users. Please ensure fair and equal access to API resources to foster a balanced ecosystem. Implement rate limiting in your application to comply with these limits, and leverage caching mechanisms where possible to optimize performance and reduce redundant requests.

For higher rate limits, contact our support team with detailed information about your use case, including the nature of your application and the expected volume of requests. This will help us tailor a solution that meets your needs while preserving the integrity of our service.

We appreciate your cooperation in maintaining our API's stability and reliability. By adhering to these guidelines, you contribute to a robust and efficient API environment that benefits every user in our community. Thank you for your understanding and support.

Common Errors

What's next?

Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the Protocol API:

• Grab your API key from the Bento dashboard
• Check out the Subscribers endpoint for adding users to your account
• Check out the Events endpoint for tracking user activity
• Check out the Emails endpoint for sending transactional emails