Online
Bento
View markdown

Subscribers

Use this API to create, import, find, and update subscribers. The batch import endpoint handles bulk additions and existing lists. The fetch endpoints look up or change individual subscribers.

Available Endpoints

MethodEndpointCopy
POST/batch/subscribers

Import Subscribers

Bulk create or update subscribers without triggering automations.

GET/fetch/search

Search Subscribers

Search subscribers by page and filters.

GET/fetch/subscribers

Find Subscriber

Fetch a subscriber by email or UUID.

POST/fetch/subscribers

Create Subscriber

Create a single subscriber record.

POST/fetch/commands

Run Command

Apply a targeted subscriber command when batch endpoints do not fit.

The Subscriber Model

The Subscriber model contains identity, profile fields, tag membership, and subscription state. Batch imports can create or update the same subscriber shape without triggering automations.

Properties

  • Name
    email
    Type
    string
    Description

    The email address for the subscriber. Bento uses this as the primary lookup key for most subscriber operations.

  • Name
    uuid
    Type
    string
    Description

    Bento's stable identifier for the subscriber.

  • Name
    first_name
    Type
    string
    Description

    The subscriber's first name when supplied.

  • Name
    last_name
    Type
    string
    Description

    The subscriber's last name when supplied.

  • Name
    fields
    Type
    object
    Description

    Custom profile fields stored on the subscriber. Use flat keys for predictable segmentation and Liquid access.

  • Name
    cached_tag_ids
    Type
    array
    Description

    Internal tag ids currently associated with the subscriber. Use tag names when writing data unless an endpoint says otherwise.

  • Name
    unsubscribed_at
    Type
    datetime|null
    Description

    Timestamp for the subscriber's unsubscribe status. null means the subscriber is currently subscribed.

  • Name
    navigation_url
    Type
    string
    Description

    Dashboard URL for reviewing the subscriber in Bento when returned by search endpoints.

POST/v1/batch/subscribers

Import Subscribers

This is the recommended way to add or update subscribers. Data is processed through Bento's import queues, so updates are usually fast but can take up to 5 minutes to appear. It works for bulk imports and single subscriber updates.

Request supports 1 to 1000 subscribers per post.
Does not trigger Flows or Automations.

Required Attributes

  • Name
    email
    Type
    string
    Description

    The Email Address for the subscriber.

Optional Attributes

  • Name
    first_name
    Type
    string
    Description

    The first name for the subscriber

  • Name
    last_name
    Type
    string
    Description

    The last name for the subscriber

  • Name
    tags
    Type
    string
    Description

    Comma separated list of tags, if a tag doesn't exist it is created.

  • Name
    remove_tags
    Type
    string
    Description

    Comma separated list of tags to remove from the subscriber.

  • Name
    utm_source
    Type
    string
    Description

    Attribution source for imported subscribers, such as newsletter or google.

  • Name
    utm_medium
    Type
    string
    Description

    Attribution medium for imported subscribers, such as email or cpc.

  • Name
    utm_campaign
    Type
    string
    Description

    Attribution campaign name for imported subscribers.

  • Name
    utm_content
    Type
    string
    Description

    Optional attribution content value for imported subscribers.

  • Name
    utm_term
    Type
    string
    Description

    Optional attribution term value for imported subscribers.

  • Name
    created_at
    Type
    datetime
    Description

    ISO 8601 timestamp to backfill when the subscriber was originally created or joined.

  • Name
    some_other_field
    Type
    string
    Description

    key / value pair for storing other fields for the subscriber.



Response

The response will contain the result count of subscribers.

  • Name
    result
    Type
    integer
    Description

    Number of subscriber records accepted for import.

GET/v1/fetch/search

Search Subscribers

Searches subscribers in your account and returns up to 100 results per page. Filter by tags or by date ranges on creation, update, last event, and unsubscribe times.

This endpoint is limited to Bento Enterprise customers only. See Plans and API access or contact support for access.
Use tag names in tags, not internal tag IDs. You can send an array or a comma-separated string like customer,lead,enterprise.
tag_names is also accepted as an alias. tag_ids still works for older integrations, but tags is the recommended param.

Required Attributes

  • Name
    page
    Type
    integer
    Description

    Page number for the search

Optional Attributes

  • Name
    tags
    Type
    array|string
    Description

    Preferred filter. Accepts an array of tag names or a comma separated string.

  • Name
    tag_names
    Type
    array|string
    Description

    Alias for tags. Accepts an array of tag names or a comma separated string.

  • Name
    tag_ids
    Type
    array|string
    Description

    Legacy compatibility filter. Accepts internal tag ids as an array or comma separated string.

  • Name
    created_at
    Type
    object
    Description

    The Creation date of the subscriber.
    gt date string - greater than date
    lt date string - less than date

  • Name
    updated_at
    Type
    object
    Description

    The update date of the subscriber
    gt date string - greater than date
    lt date string - less than date

  • Name
    last_event_at
    Type
    object
    Description

    The last event date of the subscriber.
    gt date string - greater than date
    lt date string - less than date

  • Name
    unsubscribed_at
    Type
    object
    Description

    The unsubscription date of the subscriber.
    gt date string - greater than date
    lt date string - less than date



Response

Returns a report of users that match the request.

When you search with tags or tag_names, the response metadata includes both the requested tag names and the resolved cached_tag_ids used internally for search.
  • Name
    data
    Type
    array
    Description

    JSON:API-style subscriber records. Each item contains id, type, and attributes.

  • Name
    data[].attributes.uuid
    Type
    string
    Description

    Bento UUID for the matched subscriber.

  • Name
    data[].attributes.email
    Type
    string
    Description

    Subscriber email address.

  • Name
    data[].attributes.fields
    Type
    object
    Description

    Custom subscriber fields.

  • Name
    data[].attributes.cached_tag_ids
    Type
    array
    Description

    Internal tag ids matched or attached to the subscriber.

  • Name
    meta.page
    Type
    integer
    Description

    Current result page.

  • Name
    meta.query
    Type
    object
    Description

    Search filters applied by Bento, including resolved tag names and ids when tag filters are used.

GET/v1/fetch/subscribers

Find Subscriber

Fetch a matched subscriber in your account.

Required Attributes

  • Name
    email
    Type
    string
    Description

    Email address to search for a match in your account

Optional Attributes

  • Name
    uuid
    Type
    string
    Description

    This returns the subscriber with the given identifier, though it is rarely needed. Can be used in place of email address.



Response

Returns the subscriber details.

  • Name
    data.id
    Type
    string
    Description

    Internal record id.

  • Name
    data.type
    Type
    string
    Description

    Resource type, typically visitors.

  • Name
    data.attributes.uuid
    Type
    string
    Description

    Bento UUID for the subscriber.

  • Name
    data.attributes.email
    Type
    string
    Description

    Subscriber email address.

  • Name
    data.attributes.fields
    Type
    object
    Description

    Custom fields stored on the subscriber.

  • Name
    data.attributes.cached_tag_ids
    Type
    array
    Description

    Internal tag ids attached to the subscriber.

POST/v1/fetch/subscribers

Create Subscriber

Creates a subscriber in your account and queues them for indexing.

Required Attributes

  • Name
    subscriber
    Type
    object
    Description

    An object describing the subscriber to create.
    email string - subscriber email address



Response

Returns the created subscriber's details.

  • Name
    data.id
    Type
    string
    Description

    Internal record id for the created subscriber.

  • Name
    data.type
    Type
    string
    Description

    Resource type, typically visitors.

  • Name
    data.attributes.uuid
    Type
    string
    Description

    Bento UUID for the subscriber.

  • Name
    data.attributes.email
    Type
    string
    Description

    Subscriber email address.

  • Name
    data.attributes.fields
    Type
    object
    Description

    Custom fields stored on the subscriber.

  • Name
    data.attributes.cached_tag_ids
    Type
    array
    Description

    Internal tag ids attached to the subscriber.

POST/v1/fetch/commands

Run Command

Endpoint to execute a command and change a subscriber's data.

This endpoint is not recommended for most use cases as it has a delayed response. It is recommended to use if the batch endpoints are not working for your use case.

Required Attributes

  • Name
    command
    Type
    object
    Description

    An array of command objects, each targeting one subscriber.
    command string - add_tag, add_tag_via_event, remove_tag, add_field, remove_field, subscribe, unsubscribe, change_email

    email string - subscriber email address

    query string/object - data for the requested change



Response

Returns the updated subscriber details.

  • Name
    data
    Type
    object
    Description

    Updated subscriber record, using the same shape as the find subscriber response.

  • Name
    data.attributes
    Type
    object
    Description

    Subscriber attributes after the command is applied.

Was this page useful?

Your answer helps us find docs that need work.