OpenAPI-style API reference

This browser gives you one place to scan Bento endpoints, request fields, response fields, and the matching hand-written docs. It is generated from a docs-owned OpenAPI-style snapshot that follows the current MDX reference pages.

The public bentonow/api repository may be stale. This page intentionally mirrors the current docs instead of pulling that repo at build time.

Reference browser

Base URL

https://app.bentonow.com/api/v1

Snapshot

docs-snapshot-2026-07-08

Endpoints

This snapshot is maintained from the current Bento docs pages. The public bentonow/api repository may lag behind this reference.

Core writes

Create or update Bento data from your app.

POST/batch/events

Create events

Track user activity, update profile fields, and trigger workflows.

Endpoint docs

Request

events

arrayrequired

One to 1000 event objects.

events[].type

stringrequired

Event name.

events[].email

stringrequired

Subscriber email address.

events[].fields

object

Flat profile fields to update.

events[].details

object

Nested event-specific context.

events[].date

datetime

Optional ISO 8601 timestamp for when the event happened.

Response

results

integer

Number of events accepted.

failed

integer

Number of events rejected.

POST/batch/subscribers

Import subscribers

Bulk create or update subscribers without triggering automations.

Endpoint docs

Request

subscribers

arrayrequired

One to 1000 subscriber objects.

subscribers[].email

stringrequired

Subscriber email address.

subscribers[].first_name

string

Subscriber first name.

subscribers[].last_name

string

Subscriber last name.

subscribers[].tags

string

Comma-separated tags to add.

subscribers[].remove_tags

string

Comma-separated tags to remove.

subscribers[].utm_source

string

Attribution source for imported subscribers.

subscribers[].utm_medium

string

Attribution medium for imported subscribers.

subscribers[].utm_campaign

string

Attribution campaign for imported subscribers.

subscribers[].utm_content

string

Optional attribution content value.

subscribers[].utm_term

string

Optional attribution term value.

subscribers[].created_at

datetime

ISO 8601 timestamp to backfill the subscriber creation date.

Response

results

integer

Number of subscriber records queued for import.

failed

integer

Number of subscriber records rejected from the request.

POST/batch/emails

Create emails

Queue transactional or one-off emails for delivery.

Endpoint docs

Request

emails

arrayrequired

One to 60 email objects.

emails[].to

stringrequired

Recipient email address.

emails[].from

stringrequired

Sender email address. Must be an author.

emails[].subject

stringrequired

Email subject.

emails[].html_body

stringrequired

HTML email body.

emails[].transactional

boolean

Send even if the user is unsubscribed.

emails[].personalizations

object

Liquid values for the email body.

Response

results

integer

Number of emails accepted.

POST/data_deletion_requests

Create data deletion request

Queue visitor anonymization by email for one site.

Endpoint docs

Request

site_uuid

stringrequired

Site identifier.

data_deletion_request[email]

stringrequired

Visitor email to anonymize.

Response

status

string

Returns queued_for_anonymization on success.

Subscribers

Look up and modify people in Bento.

GET/fetch/searchEnterprise

Search subscribers

Search subscribers by page and filters.

Endpoint docs

Request

page

integerrequired

Result page.

tags

array|string

Preferred tag-name filter.

created_at

object

Date filter with `gt` or `lt`.

updated_at

object

Date filter with `gt` or `lt`.

Response

data

array

Matching subscriber records.

meta.page

integer

Current result page.

meta.query

object

Filters Bento applied.

GET/fetch/subscribers

Find subscriber

Fetch a subscriber by email or UUID.

Endpoint docs

Request

email

stringrequired

Subscriber email address.

uuid

string

Subscriber UUID. Can be used instead of email.

Response

data.id

string

Internal record id.

data.attributes.uuid

string

Bento subscriber UUID.

data.attributes.email

string

Subscriber email address.

data.attributes.fields

object

Custom subscriber fields.

data.attributes.cached_tag_ids

array

Internal tag ids attached to the subscriber.

data.attributes.tags

array

Human-readable tag names attached to the subscriber.

data.attributes.unsubscribed_at

datetime|null

Subscriber unsubscribe timestamp, or null when subscribed.

data.attributes.unsubscribed_reason

string|null

Recorded unsubscribe reason, when available.

data.attributes.attribution.first_referral

string

First referral source, or an empty string when unavailable.

data.attributes.attribution.first_page

string

First page captured for the subscriber, or an empty string when unavailable.

data.attributes.attribution.campaign_data

object

First-touch campaign data. Returns {} when unset.

POST/fetch/commands

Run subscriber command

Apply targeted tag, field, subscription, or email-change commands.

Endpoint docs

Request

command

arrayrequired

Command objects to run.

command[].command

stringrequired

`add_tag`, `remove_tag`, `add_field`, `remove_field`, `subscribe`, `unsubscribe`, or `change_email`.

command[].email

stringrequired

Subscriber email address.

command[].query

string|object

Command-specific value.

Response

results

integer

Number of commands queued for async processing. Commands run in the background; this is not a synchronous subscriber update.

Segments

Read saved audience segments and check segment membership.

GET/fetch/segments

Get segments

List saved audience segments.

Endpoint docs

Response

data

array

Saved segment records.

data[].attributes.name

string

Segment name.

data[].attributes.visitor_event_query

object

Saved query definition.

GET/fetch/segments/:id

Get segment

Fetch one saved segment and its query definition.

Endpoint docs

Request

id

stringrequired

Segment id.

Response

data.id

string

Segment identifier.

data.attributes.name

string

Segment name.

data.attributes.visitor_event_query

object

Saved query definition.

POST/fetch/segments/:id/match

Match segment

Check whether an email address matches a saved segment.

Endpoint docs

Request

id

stringrequired

Segment id.

email

stringrequired

Subscriber email address.

Response

data.segment_id

string

Segment identifier.

data.email

string

Normalized email address Bento checked.

data.match

boolean

Whether the subscriber matches the segment.

Definitions

Manage tag and field definitions.

GET/fetch/tags

Get tags

List tag definitions in your account.

Endpoint docs

Response

data

array

Tag records.

POST/fetch/tags

Create tag

Create one custom tag definition.

Endpoint docs

Request

name

stringrequired

Tag name.

Response

data.name

string

Created tag name.

DELETE/fetch/tags/:id

Delete tag

Discard one tag definition by name.

Endpoint docs

Request

id

stringrequired

Tag id from the list tags response.

tag.name

stringrequired

Tag name to discard or restore.

Response

message

string

Deletion or restoration status message.

GET/fetch/fields

Get fields

List custom field definitions.

Endpoint docs

Response

data

array

Field records.

POST/fetch/fields

Create field

Create one custom profile field.

Endpoint docs

Request

key

stringrequired

Field key.

Response

data.name

string

Created field key.

Marketing content

Read and modify campaign, sequence, workflow, and template records.

GET/fetch/broadcasts

Get broadcasts

List broadcast history and draft or scheduled broadcast metadata.

Endpoint docs

Request

page

integer

Result page.

status

string

`sent`, `draft`, `sending`, `scheduled`, `paused`, or `canceled`.

Response

data

array

Broadcast records.

POST/batch/broadcasts

Create broadcasts

Create broadcast campaigns for a segment or tag audience.

Endpoint docs

Request

broadcasts

arrayrequired

Broadcast objects to create.

broadcasts[].name

stringrequired

Campaign name.

broadcasts[].subject

stringrequired

Subject line.

broadcasts[].content

stringrequired

Email body.

Response

results

integer

Broadcasts accepted for processing.

GET/fetch/sequences

Get sequences

List sequences and attached email templates.

Endpoint docs

Response

data

array

Sequence records.

data[].id

string

Sequence ID to use in create URLs.

data[].attributes.email_templates

array

Embedded email templates with id, subject, and stats.

POST/fetch/sequences/:id/emails/templates

Create sequence email

Add a new email template to a sequence. Use the id returned by Get sequences in :id.

Endpoint docs

Request

id

stringrequired

Sequence id returned by Get sequences.

site_uuid

stringrequired

Site identifier.

email_template.subject

stringrequired

Subject line for the new sequence email.

email_template.html

stringrequired

HTML body for the email.

email_template.delay_interval

string

Delay unit: minutes, hours, days, or months.

email_template.delay_interval_count

integer

Delay amount paired with delay_interval.

email_template.inbox_snippet

string

Optional preview text snippet.

Response

data.id

integer

Created email template ID.

data.attributes.subject

string

Created subject line.

data.attributes.html

string

Created HTML content.

GET/fetch/workflows

Get workflows

List workflows and attached email templates. Read-only.

Endpoint docs

Response

data

array

Workflow records.

GET/fetch/emails/templates/:id

Get email template

Fetch one email template with HTML and stats.

Endpoint docs

Request

id

integerrequired

Template id.

Response

data.attributes

object

Template content and stats.

PATCH/fetch/emails/templates/:id

Update email template

Update the subject or HTML for one template.

Endpoint docs

Request

id

integerrequired

Template id.

email_template.subject

string

Updated subject.

email_template.html

string

Updated HTML.

Response

data.attributes

object

Updated template content.

Stats and validation

Read reporting data and validate risky inputs.

GET/stats/site

Get site stats

Fetch top-level site subscriber statistics.

Endpoint docs

Response

user_count

integer

Total users.

subscriber_count

integer

Active subscribers.

unsubscriber_count

integer

Unsubscribed users.

GET/stats/segment

Get segment stats

Fetch subscriber statistics for one saved segment.

Endpoint docs

Request

site_uuid

stringrequired

Site identifier.

segment_id

stringrequired

Segment identifier.

Response

user_count

integer

Total users in the segment.

subscriber_count

integer

Active subscribers in the segment.

unsubscriber_count

integer

Unsubscribed users in the segment.

GET/stats/report

Get report stats

Fetch data for one saved report.

Endpoint docs

Request

site_uuid

stringrequired

Site identifier.

report_id

stringrequired

Report identifier.

Response

data

object

Report statistics payload.

GET/stats/ads

Get ads stats

Fetch signup, customer, and revenue attribution by UTM or ad dimension.

Endpoint docs

Request

site_uuid

stringrequired

Site identifier.

dimension

string

source, campaign, medium, content, or ad. Defaults to source.

value

string

Exact dimension value to filter to.

start_date

string

Reporting window start. Natural language accepted.

end_date

string

Reporting window end. Defaults to now.

revenue_mode

string

all_revenue, first_revenue, or subscriptions. Defaults to all_revenue.

Response

dimension

string

Attribution dimension used for grouping.

totals

object

Signup, customer, and revenue totals.

breakdown

array

Ranked attribution rows. Money values are in cents.

GET/experimental/blacklist

Search blacklists

Check a domain or IPv4 address against email reputation blacklists.

Endpoint docs

Request

domain

string

Domain to check, such as example.com.

ip

string

IPv4 address to check.

Response

results

object|null

Boolean flags per reputation service, or null when all checks pass.

POST/experimental/validation

Validate email

Return a conservative valid or invalid result for signup forms.

Endpoint docs

Request

email

stringrequired

Email address to validate.

name

string

Optional contact name to screen.

Response

valid

boolean

Whether Bento considers the signup valid.

POST/experimental/jesses_ruleset

Validate email strict

Run Bento stricter internal validation ruleset for signup review flows.

Endpoint docs

Request

email

stringrequired

Email address to validate.

block_free_providers

boolean

Reject free email providers when true.

wiggleroom

boolean

Relax some opinionated checks when true.

Response

valid

boolean

Pass or fail result.

reasons

array

Human-readable rejection reasons.

POST/experimental/content_moderation

Moderate content

Check small text payloads for risky content.

Endpoint docs

Request

content

stringrequired

Text to moderate.

Response

valid

boolean

Whether the content is safe.

reasons

array

Detected issues.

POST/experimental/gender

Guess gender

Guess likely gender from a first name. Best-effort helper only.

Endpoint docs

Request

name

stringrequired

First name to evaluate.

Response

gender

string

Likely gender label returned by the model.

GET/experimental/geolocation

Geolocate IP address

Legacy geolocation endpoint. GeoIP lookup is disabled and returns an empty object.

Endpoint docs

Request

ip

stringrequired

IPv4 address. Accepted for compatibility.

Response

(empty object)

object

Returns `{}`. Do not rely on this endpoint for location data.

How this snapshot works

The snapshot lives in site/data/docs/openapi-reference.js. Hand-written endpoint pages remain the source for deeper examples, caveats, and operational notes. Use this browser for quick schema lookup, then open the endpoint docs for implementation details.