Bento
View markdown

Segments

Use the Segments API to fetch saved audience segments from your Bento account. This is useful when you want to inspect available segments, sync them into your own tooling, or fetch a segment's saved query before using it elsewhere.

The public Segments API is read-only. Create and edit segments in the Bento app, then use these endpoints to inspect them from your own tooling.

Available Endpoints

MethodEndpointCopy
GET
/fetch/segments

Get Segments

List saved audience segments.

GET
/fetch/segments/:id

Get Segment

Fetch one saved segment and its query definition.

POST
/fetch/segments/:id/match

Match Segment

Check whether an email address matches a saved segment.

The Segment Model

A segment is a saved audience definition based on Bento filters and events. The API returns the saved segment metadata along with the underlying visitor_event_query JSON used to define the segment.

Properties

  • Name
    idstring
    Description

    The segment identifier.

  • Name
    namestring
    Description

    The segment name.

  • Name
    descriptionstring
    Description

    Optional description for the segment.

  • Name
    visitor_event_queryobject
    Description

    The saved query definition for the segment.

  • Name
    created_atdatetime
    Description

    When the segment was created.

  • Name
    updated_atdatetime
    Description

    When the segment was last updated.

GET/v1/fetch/segments

Get Segments

Returns all saved segments in your account, ordered by name.

Only kept segments are returned. Deleted or discarded segments are excluded.


Response

Returns a list of segment objects.

  • Name
    dataarray
    Description

    Saved segment records.

  • Name
    data[].idstring
    Description

    Segment identifier.

  • Name
    data[].namestring
    Description

    Segment name.

  • Name
    data[].visitor_event_queryobject
    Description

    Saved query definition for the segment.

GET/v1/fetch/segments/:id

Get Segment

Returns one saved segment by id.

Required Attributes

  • Name
    idstring
    Description

    The segment id to fetch.



Response

Returns the segment details, including its saved visitor_event_query.

  • Name
    data.idstring
    Description

    Segment identifier.

  • Name
    data.namestring
    Description

    Segment name.

  • Name
    data.descriptionstring
    Description

    Segment description when one is set.

  • Name
    data.visitor_event_queryobject
    Description

    Saved query definition for the segment.

POST/v1/fetch/segments/:id/match

Match Segment

Checks whether one email address matches a saved segment. Send the email address in the JSON request body.

Bento looks up the email on the authenticated site only. If the email is not a subscriber on that site, the response returns match: false.

Required Attributes

  • Name
    idstring
    Description

    The segment id to check.

  • Name
    emailstring
    Description

    The email address to match against the segment. This must be sent in the JSON request body, not as a query string.



Response

Returns a boolean result for the email and segment. Bento normalizes the email before checking it.

  • Name
    data.segment_idstring
    Description

    Segment identifier.

  • Name
    data.emailstring
    Description

    Normalized email address Bento checked.

  • Name
    data.matchboolean
    Description

    Whether the subscriber matches the saved segment.

Missing or invalid email addresses return 422. Bento may return 429 if there are too many match requests for the same segment.