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
    emailstring
    Description

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

  • Name
    uuidstring
    Description

    Bento's stable identifier for the subscriber.

  • Name
    first_namestring
    Description

    The subscriber's first name when supplied.

  • Name
    last_namestring
    Description

    The subscriber's last name when supplied.

  • Name
    fieldsobject
    Description

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

  • Name
    cached_tag_idsarray
    Description

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

  • Name
    unsubscribed_atdatetime|null
    Description

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

  • Name
    navigation_urlstring
    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
    emailstring
    Description

    The Email Address for the subscriber.

Optional Attributes

  • Name
    first_namestring
    Description

    The first name for the subscriber

  • Name
    last_namestring
    Description

    The last name for the subscriber

  • Name
    tagsstring
    Description

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

  • Name
    remove_tagsstring
    Description

    Comma separated list of tags to remove from the subscriber.

  • Name
    utm_sourcestring
    Description

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

  • Name
    utm_mediumstring
    Description

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

  • Name
    utm_campaignstring
    Description

    Attribution campaign name for imported subscribers.

  • Name
    utm_contentstring
    Description

    Optional attribution content value for imported subscribers.

  • Name
    utm_termstring
    Description

    Optional attribution term value for imported subscribers.

  • Name
    created_atdatetime
    Description

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

  • Name
    lifetime_value_currencystring
    Description

    Three-letter currency code for the subscriber's lifetime value, such as USD.

  • Name
    lifetime_value_amountinteger
    Description

    Lifetime value amount in cents. For example, USD $10 should be 1000.

  • Name
    some_other_fieldstring
    Description

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

CSV import example:

Code
email,lifetime_value_currency,lifetime_value_amount
jane@example.com,USD,1000


Response

The response will contain the result count of subscribers.

  • Name
    resultinteger
    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
    pageinteger
    Description

    Page number for the search

Optional Attributes

  • Name
    tagsarray|string
    Description

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

  • Name
    tag_namesarray|string
    Description

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

  • Name
    tag_idsarray|string
    Description

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

  • Name
    created_atobject
    Description

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

  • Name
    updated_atobject
    Description

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

  • Name
    last_event_atobject
    Description

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

  • Name
    unsubscribed_atobject
    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
    dataarray
    Description

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

  • Name
    data[].attributes.uuidstring
    Description

    Bento UUID for the matched subscriber.

  • Name
    data[].attributes.emailstring
    Description

    Subscriber email address.

  • Name
    data[].attributes.fieldsobject
    Description

    Custom subscriber fields.

  • Name
    data[].attributes.cached_tag_idsarray
    Description

    Internal tag ids matched or attached to the subscriber.

  • Name
    meta.pageinteger
    Description

    Current result page.

  • Name
    meta.queryobject
    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
    emailstring
    Description

    Email address to search for a match in your account

Optional Attributes

  • Name
    uuidstring
    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.idstring
    Description

    Internal record id.

  • Name
    data.typestring
    Description

    Resource type, typically visitors.

  • Name
    data.attributes.uuidstring
    Description

    Bento UUID for the subscriber.

  • Name
    data.attributes.emailstring
    Description

    Subscriber email address.

  • Name
    data.attributes.fieldsobject
    Description

    Custom fields stored on the subscriber.

  • Name
    data.attributes.cached_tag_idsarray
    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
    subscriberobject
    Description

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



Response

Returns the created subscriber's details.

  • Name
    data.idstring
    Description

    Internal record id for the created subscriber.

  • Name
    data.typestring
    Description

    Resource type, typically visitors.

  • Name
    data.attributes.uuidstring
    Description

    Bento UUID for the subscriber.

  • Name
    data.attributes.emailstring
    Description

    Subscriber email address.

  • Name
    data.attributes.fieldsobject
    Description

    Custom fields stored on the subscriber.

  • Name
    data.attributes.cached_tag_idsarray
    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
    commandobject
    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
    dataobject
    Description

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

  • Name
    data.attributesobject
    Description

    Subscriber attributes after the command is applied.