Developer API Documentation
Search…
API v1 — Fetch Endpoint
API V1 - Batch Endpoint
API V1 (Experimental)
Multi-Query Example
This is a short example that showcases a few endpoints most API users will need.
The following guide uses basic Ruby in it's examples. You can use any language of choice in your implementation.
Just make sure that you remember to keep your API keys safe and secure 🙏
Basics
To access data in Bento, you'll need three things:
- Your Site Key/UUID.
- Your user's Private API Key.
- Your user's Public API Key.
You can expire your Private and Public Keys but cannot expire your Site Key without a support request. All requests to our API are logged and monitored for anomalies.
Rate Limiting
All requests to
fetch have a maximum of 3,600 requests per hour.All requests to
batch have a maximum of 500 requests per hour.Typical Issues
When we chat to developers we typically see a few issues come up when interacting with the API.
The most common issue is incorrect API or Site Keys. If you can't find them, you can raise a support ticket or ask us in Discord and we'll find them for you.
The second most common issue is hitting rate limits (described above). Please make sure you're using the appropriate endpoint for whatever task you are doing in Bento.
With all that said, let's begin the example!
To begin, let's start wth using the
fetch/subscribers endpoint to add a new visitor record into Bento via their email address. In Bento, a subscriber is essentially a visitor with an email added to their profile.
A
GET request to this endpoint will simply try to find a visitor who has the email you specified to confirm that they have been synced whereas a POST request will either lookup the visitor or create it by email. For almost all cases, you will want to POST to the endpoint.create_subscriber.rb
1
require 'net/http'
2
require 'uri'
3
4
publishable_key = "XXXX-XXXX-XXXX-XXXX"
5
secret_key = "XXXX-XXXX-XXXX-XXXX"
6
site_uuid = "XXXX-XXXX-XXXX-XXXX"
7
8
uri = URI.parse("https://app.bentonow.com/api/v1/fetch/subscribers")
9
request = Net::HTTP::Post.new(uri)
10
request.basic_auth(publishable_key, secret_key)
11
request.body = JSON.dump({site_uuid: site_uuid, email: "[email protected]"})
12
request.content_type = "application/json"
13
req_options = { use_ssl: uri.scheme == "https", }
14
15
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
16
http.request(request)
17
end
18
19
puts JSON.parse(response.body)
Copied!
After running this we will get a response confirming the visitor was added and their details.
1
{"data"=>{"id"=>"568", "type"=>"visitors", "attributes"=>{"uuid"=>"9b91f034d6692e3ec61830705ceef818", "email"=>"[email protected]", "fields"=>nil, "cached_tag_ids"=>[]}}}
Copied!
Now, let's add some data to the profile without triggering any automations.
The visitor has now been added to Bento so we're going to want to flesh out their profile with some more detail.
Let's add a
customer tag to the profile using the fetch/commands endpoint. We will be using the
add_tag command instead of the add_tag_via_query as we do not want to fire any automations.add_tag.rb
1
uri = URI.parse("https://app.bentonow.com/api/v1/fetch/commands")
2
request = Net::HTTP::Post.new(uri)
3
request.basic_auth(publishable_key, secret_key)
4
request.body = JSON.dump({site_uuid: site_uuid, command: {"command": "add_tag", "email": "[email protected]", "query": "example" }})
5
request.content_type = "application/json"
6
req_options = { use_ssl: uri.scheme == "https", }
7
8
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
9
http.request(request)
10
end
11
12
puts JSON.parse(response.body)
Copied!
After running this we'll see that the tag has been added.
1
{"data"=>{"id"=>"569", "type"=>"visitors", "attributes"=>{"uuid"=>"29114b07bcfedbff608e5223e88fadc0", "email"=>"[email protected]", "fields"=>nil, "cached_tag_ids"=>["233"]}}}
Copied!
The ID that you see in the
cached_tag_ids field can be looked up via the fetch/tags endpoint if you need it. In later API updates we may put the names of the tags in this response but have avoided it for now to optimize the request.
Next, let's add a name to the visitor using the
fetch/commands endpoint again.add_custom_field.rb
1
uri = URI.parse("https://app.bentonow.com/api/v1/fetch/commands")
2
request = Net::HTTP::Post.new(uri)
3
request.basic_auth(publishable_key, secret_key)
4
request.body = JSON.dump({site_uuid: site_uuid, email: "[email protected]", command: {"command": "add_field", "email": "[email protected]", "query": {key: "name", value: "Jesse"} }})
5
request.content_type = "application/json"
6
req_options = { use_ssl: uri.scheme == "https", }
7
8
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
9
http.request(request)
10
end
11
12
puts JSON.parse(response.body)
Copied!
Great! Looks like the visitor now has a
customer tag and name added. 1
{"data"=>{"id"=>"569", "type"=>"visitors", "attributes"=>{"uuid"=>"29114b07bcfedbff608e5223e88fadc0", "email"=>"[email protected]", "fields"=>{"name"=>"Jesse"}, "cached_tag_ids"=>["233"]}}}
Copied!
They're now ready to receive email marketing!
If you visit the dashboard you'll be able to search for this visitor by any of the data you've added. These endpoints are processed and synced to our search engine within 5-15 seconds most of the time.
Let's backfill all our old data.
Now that the above code is sending in user data in real-time it's time to upload all our old subscribers.
For this, we use our
batch/subscribers endpoint.This takes in an array of subscriber information and queues it up quickly to our importer background jobs. This generally processes over a period of 5 to 50 minutes depending on the queue size, if our importer servers are warm, and how many you're adding.
import_subscribers.rb
1
import_data = [
2
{ email: "[email protected]", name: "Jesse", customer_id: "123", favourite_food: "onigiri" },
3
{ email: "[email protected]", name: "Scott", customer_id: "124" },
4
]
5
6
uri = URI.parse("https://app.bentonow.com/api/v1/batch/subscribers")
7
request = Net::HTTP::Post.new(uri)
8
request.basic_auth(publishable_key, secret_key)
9
request.body = JSON.dump({site_uuid: site_uuid, subscribers: import_data })
10
request.content_type = "application/json"
11
req_options = { use_ssl: uri.scheme == "https", }
12
13
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
14
http.request(request)
15
end
16
17
puts JSON.parse(response.body)
Copied!
Once this runs the data will be added to a queue and you will see a count as the response. No further action is required and you can just wait for the import to finish running in your account.
Let's get some event data into the system.
1
publishable_key = "XXXX-XXXX-XXXX-XXXX"
2
secret_key = "XXXX-XXXX-XXXX-XXXX"
3
site_uuid = "XXXX-XXXX-XXXX-XXXX"
4
5
import_data = [
6
{ email: "[email protected]", type: "$custom_event", fields: {"first_name": "Jesse"}, details: {"custom_stat": 1000}},
7
{ email: "[email protected]", type: "$custom_event_with_no_details", fields: {"first_name": "Jesse", "last_name": "Hanley"}},
8
{ email: "[email protected]", type: "$custom_event_with_workflow_bypass", details: {"bypass_workflows": 'true'}},
9
{ email: "[email protected]", type: "$custom_event_with_nothing_else"},
10
{ email: "[email protected]", type: "$purchase", fields: {"first_name": "Jesse"}, details: {"unique": {"key": "test123" }, "value": {"currency": "USD", "amount": 8000}}},
11
{ email: "[email protected]", type: "$purchase", fields: {"first_name": "Jesse"}, details: {"unique": {"key": "test123" }, "value": {"currency": "USD", "amount": 8000}, 'cart' => { 'items' => [{'product_sku': 'SKU123', 'product_name': 'Test', 'quantity': 100 }], 'abandoned_checkout_url': "https://test.com" }}},
12
{ email: "[email protected]", type: "$backdated_event", date: 3.years.ago }
13
]
14
15
uri = URI.parse("https://app.bentonow.com/api/v1/batch/events")
16
17
request = Net::HTTP::Post.new(uri)
18
request.basic_auth(publishable_key, secret_key)
19
request.body = JSON.dump({site_uuid: site_uuid, events: import_data })
20
request.content_type = "application/json"
21
req_options = { use_ssl: uri.scheme == "https", }
22
23
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
24
http.request(request)
25
end
26
27
puts JSON.parse(response.body)
Copied!
In the above script, we're including new events, old events, and events that bypass automations. Without the bypass key we'd expect them to trigger every Workflow that's turned on.
Last modified 2mo ago